I think, the main reason why it broke in the past, is that this.host and this.connection are a nullable type, (they are supposed to be null in certain circumstainces like refreshing), but function calls like this._setHealthListeners(this.host, this.connection); are not treating them as nullable. Imagine if this is TypeScript, it would complain that _setHealthListeners expects Host, Connection as argument while this call passes Host?, Connection?. So, aside from the _refreshInProgress flag to make sure only one refresh is happening at one time, I think we should still make sure we are using this.host and this.connection as nullable. That means this._setHealthListeners(this.host, this.connection); should be

if (this.host && this.connection){
this._setHealthListeners(this.host, this.connection);
}

And other places that access this.host and this.connection should also has null guards, like this. What do you think?

As far as I can tell, the nullability is meant to be a transient state and trying to impose these silent null checks may just cause more subtle bugs than it solves? I wouldn't be against explicit null checks in _setHealthListeners as an assertion, but simply ignoring setting the listeners could be problematic

in an ideal world we may want to use an explicit state machine but that seems pretty out of scope for this PR

Why

silent null checks may just cause more subtle bugs

?
I think they can potentially fix some bugs that we didn't discover yet.
But either way, I'm good. I think this PR can already fix the problem that we clearly know of.
If you fix that eslint error, I will give the explicit approval.

Why

silent null checks may just cause more subtle bugs

? I think they can potentially fix some bugs that we didn't discover yet. But either way, I'm good. I think this PR can already fix the problem that we clearly know of. If you fix that eslint error, I will give the explicit approval.

Just to step back for a second we need to decide if it's even valid to get to the end of _refresh() without the host or the connection being set

I don't think it should be, no?

Meaning if it happens, we're just enabling the bug to propagate silently instead of catching it and yelling to the user that that's happened and needs to be patched (which it really should never happen with this refresh fix or there's a bigger issue)

No it shouldn't reach the end of _refresh without this.host set.
You convinced me 👍

This test failure is new and it concerns me.

  1) ControlConnection
       #init()
         should subscribe to SCHEMA_CHANGE events and refresh keyspace information:
     Error: Condition still false after 100 attempts: () => cc.metadata.keyspaces['sample_change_1'].strategyOptions.replication_factor === '2'
      at whilstItem (test/test-helper.js:769:23)
      at Timeout.next [as _onTimeout] (lib/utils.js:1042:5)
      at listOnTimeout (node:internal/timers:585:17)
      at process.processTimers (node:internal/timers:521:7)

After some investigation, I think the problem is that a schema refresh triggered by an event can be permanently lost if the CC's connection is down at that moment and cannot establish new connection within 2 seconds. And this singleton refresh implementation makes it more vulnerable than before.

What might have happened:

In CI, a brief TCP hiccup (or Cassandra-side connection reset) closed the CC's socket during the 100ms debounce window after the ALTER KEYSPACE event:

1. ALTER KEYSPACE fires → SCHEMA_CHANGE event → EventDebouncer starts 100ms timer
2. TCP socket closes → socketClose → _refresh() acquires _refreshInProgress, sets this.connection = null
3. Debouncer fires → metadata.refreshKeyspace → cc.query() → connection === null → _waitForReconnection() (2s timeout)
4. _refresh() fails or does not establish new connection within 2 seconds -> _waitForReconnection rejects
5. Error is swallowed by toBackground() — the ALTER KEYSPACE schema update is silently dropped
6. CC eventually reconnects but no new SCHEMA_CHANGE event arrives → keyspace stays at replication_factor=3 → poll times out

In the past, when we accidentally allowed concurrent _refresh() calls, If one concurrent attempt succeeded while another failed, the newConnection(null) event would resolve the pending _waitForReconnection before the error could reject it. The new singleton approach eliminates that accidental rescue path.

Fix

Instead of allowing concurrent refresh, I think we should fix the problem of schema refresh errors being swallowed. For example, in control-connection.js _nodeSchemaChangeHandler

  // Instead of: toBackground(this.handleSchemaChange(event, false))
  this.handleSchemaChange(event, false).catch(() => {
    // CC will reconnect; re-queue this event once it does
    this.once('newConnection', (err) => {
      if (!err) toBackground(this.handleSchemaChange(event, false));
    });
  });

Bret points out that the Java driver's behavior is that every time a new control connection is established, it refreshes schema

https://github.com/apache/cassandra-java-driver/blob/90b09e0e34fd6fdda064f13f6acd0df7268a3dc6/core/src/main/java/com/datastax/oss/driver/internal/core/control/ControlConnection.java#L460-L469

It makes sense to me that Node.js driver can align with Java driver's behavior.
That would be an easier fix, too.

diff --git a/lib/control-connection.js b/lib/control-connection.js
index 5abf8b06..4199281c 100644
--- a/lib/control-connection.js
+++ b/lib/control-connection.js
@@ -415,6 +415,8 @@ class ControlConnection extends events.EventEmitter {
 
       await this.metadata.refreshKeyspacesInternal(false);
       this.metadata.initialized = true;
+    } else if (this.options.isMetadataSyncEnabled) {
+    await this.metadata.refreshKeyspacesInternal(false);
     }
   }

After some deliberation we think we can just call this.metadata.refreshKeyspaces[Internal?]() within _refreshHosts unconditionally as that function appears to invalidate all such schema caches. Need to triple check if this is the right solution thoguh

Confirming above is correct.
The question is whether refreshKeyspacesInternal is enough to cover any EVENTs potentially lost.
There are 3 kinds of EVENTs

1. TOPOLOGY_CHANGE, handled by refreshHosts
2. STATUS_CHANGE, a host UP or DOWN, is handled by host.js's reconnection schedule, independent from ControlConnection
3. SCHEMA_CHANGE
   3a. refreshKeyspacesInternal redo SELECT * FROM system_schema.keyspaces
   3b. It also removes the cache for udt, table, function, aggregate, and views. They will be lazy-loaded when used for the first time.
   So I think refreshKeyspacesInternal is enough.